<!DOCTYPE html>
<HTML>
<HEAD><meta name="viewport" content="width=device-width, initial-scale=1">
<Title>Zooming and Scrolling Framework</Title>
<link type='text/css' rel='Stylesheet' href="maxchartapi.css" />
</HEAD>
<body bgcolor="#FFFFFF" text="#000000" topmargin="0" leftmargin="0" rightmargin="0" marginwidth="0" marginheight="0">
<p class="heading0">ChartDirector 7.0 (Java Edition)</p>
<p class="heading1">Zooming and Scrolling Framework</p>
<hr class="separator">
<p class="heading1aa">Introduction</p><div class="content">
The ChartDirector Zooming and Scrolling Framework is a framework for "logical zooming" of charts. "Logical zooming" means the chart is plotted with more details as it is zoomed in, but the chart objects do not necessary become bigger. The font size, line width, symbol size, etc, may remain the same. The chart may change type or use different data when it is zoomed in. For example, for a finance chart, it may start as a daily candlestick chart when the time range is long, and becomes a realtime intraday line chart when zoomed to one day.<br><br>
The main elements of the ChartDirector Zooming and Scrolling Framework include a click and drag user interface to control zooming and scrolling, a set of methods to manage axis scales, and AJAX support to allow updating charts without refreshing the web page.
</div><p class="heading1a">WebChartViewer and JsChartViewer</p><div class="content">
The ChartDirector Zooming and Scrolling Framework for web applications is implemented in a server side control and a browser side control.<br><br>
<ul>
<li><a href="WebChartViewer.htm">WebChartViewer</a> : This is the server side control for ASP.NET Web Forms. It handles AJAX communications with the JsChartViewer on the browser side.<br><br>
<li><a href="JsChartViewer.htm">JsChartViewer</a> : This is a browser side Javascript control that provides the click and drag user interface to control zooming and scrolling. It communicates with the WebChartViewer on the server side using AJAX means to update the chart.<br></ul>
For a typical web page with a zoomable and scrollable chart, the operation is as follows:<br><br>
<ul>
<li>The browser sends a request to the server for the web page.<br><br>
<li>On the server side, the charting code creates the chart and assigns it to the <a href="WebChartViewer.htm">WebChartViewer</a>. The WebChartViewer would then generated the HTML for the chart, with other necessary information to support zooming and scrolling and AJAX communications.<br><br>
<li>The browser receives the web page from the server and displays the chart. The user can then use mouse or touch actions to zoom or scroll the chart.<br><br>
<li>When a zooming or scrolling action occurs, the JsChartViewer will send an AJAX request to the server to update the chart.<br><br>
<li>On the server side, a new chart is generated based on the updated axis scale, and the WebChartViewer returns it to the browser as an AJAX response. The browser can then display the updated chart to the user.<br></ul>
The last three steps may repeat as the user continues to zoom or scroll the chart.<br><br>
The above is only a brief description and omit many details. For example, custom parameters may be included in the AJAX request/response. Besides mouse or touch actions on the chart, the framework allows using external controls or custom methods for zooming and scrolling. In addition to updating the chart, the framework allows other custom things to be updated. These features will be discussed in the following sections.
</div><p class="heading1a">The View Port</p><div class="content">
In the ChartDirector Zooming and Scrolling framework, the view port is used to determine which part of the data range should be plotted.<br><br>
The view port can be imagined as a rectangular window over the entire XY data range. For example, suppose the full data range is 10 years in the horizontal direction. A view port width of 0.1 means only 10% of the horizontal data range should be plotted. In other words, the chart is zoomed in so that only 1 year of data is visible. The view port left side will determine exactly which year of data that is visible.<br><br>
The view port position and size can be get and set on both the server side and the client side using the following methods. The full data range is always assumed to be 0 to 1. So the view port position and size should be between 0 to 1.
</div><p class="heading2">Server Side Methods</p><div class="content">
<div class="overflowblock"> <div style="width:100%;box-sizing:border-box;"><table width="100%" border="1" cellpadding="5" cellspacing="0"> <tr><th width="33%">Method<th>Description
<tr><td><a href="WebChartViewer.getViewPortLeft.htm">WebChartViewer.getViewPortLeft</a><td>Gets the position of the left side of the view port. <tr><td><a href="WebChartViewer.setViewPortLeft.htm">WebChartViewer.setViewPortLeft</a><td>Sets the position of the left side of the view port. <tr><td><a href="WebChartViewer.getViewPortTop.htm">WebChartViewer.getViewPortTop</a><td>Gets the position of the top side of the view port. <tr><td><a href="WebChartViewer.setViewPortTop.htm">WebChartViewer.setViewPortTop</a><td>Sets the position of the top side of the view port. <tr><td><a href="WebChartViewer.getViewPortWidth.htm">WebChartViewer.getViewPortWidth</a><td>Gets the width of the view port. <tr><td><a href="WebChartViewer.setViewPortWidth.htm">WebChartViewer.setViewPortWidth</a><td>Sets the width of the view port. <tr><td><a href="WebChartViewer.getViewPortHeight.htm">WebChartViewer.getViewPortHeight</a><td>Gets the height of the view port. <tr><td><a href="WebChartViewer.setViewPortHeight.htm">WebChartViewer.setViewPortHeight</a><td>Sets the height of the view port.
</table></div> </div></div><p class="heading2">Browser Side Methods</p><div class="content">
<div class="overflowblock"> <div style="width:100%;box-sizing:border-box;"><table width="100%" border="1" cellpadding="5" cellspacing="0"> <tr><th width="33%">Method<th>Description
<tr><td><a href="JsChartViewer.getViewPortLeft.htm">JsChartViewer.getViewPortLeft</a><td>Gets the position of the left side of the view port. <tr><td><a href="JsChartViewer.setViewPortLeft.htm">JsChartViewer.setViewPortLeft</a><td>Sets the position of the left side of the view port. <tr><td><a href="JsChartViewer.getViewPortTop.htm">JsChartViewer.getViewPortTop</a><td>Gets the position of the top side of the view port. <tr><td><a href="JsChartViewer.setViewPortTop.htm">JsChartViewer.setViewPortTop</a><td>Sets the position of the top side of the view port. <tr><td><a href="JsChartViewer.getViewPortWidth.htm">JsChartViewer.getViewPortWidth</a><td>Gets the width of the view port. <tr><td><a href="JsChartViewer.setViewPortWidth.htm">JsChartViewer.setViewPortWidth</a><td>Sets the width of the view port. <tr><td><a href="JsChartViewer.getViewPortHeight.htm">JsChartViewer.getViewPortHeight</a><td>Gets the height of the view port. <tr><td><a href="JsChartViewer.setViewPortHeight.htm">JsChartViewer.setViewPortHeight</a><td>Sets the height of the view port.
</table></div> </div></div><p class="heading1a">The Zoom and Scroll User Interface</p><div class="content">
The <a href="JsChartViewer.htm">JsChartViewer</a> control allows using mouse actions on the chart to control zooming and scrolling. Several mouse usage modes are supported, including drag to scroll, drag to select a region to zoom into, click to zoom in, and click to zoom out. They can be selected using <a href="JsChartViewer.setMouseUsage.htm">JsChartViewer.setMouseUsage</a>. The zooming and scrolling direction can be horizontal only, vertical only, or both, configurable using <a href="JsChartViewer.setZoomDirection.htm">JsChartViewer.setZoomDirection</a> and <a href="JsChartViewer.setScrollDirection.htm">JsChartViewer.setScrollDirection</a>.<br><br>
When the user performs zooming or scrolling, <a href="JsChartViewer.htm">JsChartViewer</a> will update the view port to reflect the new visible region and fires the <a href="JsChartViewer.ViewPortChanged.htm">JsChartViewer.ViewPortChanged</a> event. In typical usage, <a href="JsChartViewer.attachHandler.htm">JsChartViewer.attachHandler</a> can be used to attach <a href="JsChartViewer.partialUpdate.htm">JsChartViewer.partialUpdate</a> as the ViewPortChanged event handler. This will cause an AJAX request to be sent to the server to update the chart when the view port changes.
</div><p class="heading1a">WebViewPortControl and JsViewPortControl</p><div class="content">
In addition to using mouse or touch actions directly on the chart being zoomed or scrolled, ChartDirector provides the <a href="WebViewPortControl.htm">WebViewPortControl</a>  and <a href="JsViewPortControl.htm">JsViewPortControl</a> to let users visualize and manipulate the view port managed by the <a href="JsChartViewer.htm">JsChartViewer</a>. The WebViewPortControl works on the server side. The JsViewPortControl is the corresponding browser side Javascript control.<br><br>
In typical usage, the WebViewPortControl displays an "overall chart" that shows the full data range. On the browser side, the JsViewPortControl connects with the JsChartViewer using <a href="JsViewPortControl.setViewer.htm">JsViewPortControl.setViewer</a>. The JsViewPortControl can then include a rectangle on the overall chart to represent the view port. The user can drag the rectangle to move the view port, which corresponds to scrolling. The user can also drag the rectangle border to resize the view port, which corresponds to zooming. In additional, the user can drag a new rectangular region as the new view port or click on a point on the overall chart to center the view port at that point. These user interactions can be configured with the methods of the WebViewPortControl or JsViewPortControl.
</div><p class="heading1a">Zoom and Scroll with External Controls</p><div class="content">
In some applications, it may be desirable to have other ways to control zooming and scrolling. For example, in finance charts, there are often links that allow the user to jump to certain predefined period (eg. the last 30, 90, 180 or 360 days), which are essentially a type of zooming and scrolling.<br><br>
To perform zooming and scrolling using external controls, the controls can update the view port position and size, and then fire the <a href="JsChartViewer.ViewPortChanged.htm">JsChartViewer.ViewPortChanged</a> event by using <a href="JsChartViewer.raiseViewPortChangedEvent.htm">JsChartViewer.raiseViewPortChangedEvent</a>.<br><br>
In some cases, the updates may need to be bi-directional - that is, the external controls may need to be updated when the view port changes. For example, suppose a scrollbar control is used to scroll the chart. When the user drags on the scrollbar, it can update the view port. The user may also drag on the chart directly to scroll the chart. In this case, the scrollbar would need to be updated to reflect that the changed view port.<br><br>
To handle updating external controls when the view port changes, one may use the <a href="JsChartViewer.PostUpdate.htm">JsChartViewer.PostUpdate</a> event. This event occurs after the server has responded to the AJAX request from the browser, at which stage the view port should have been confirmed and validated by the server. External controls can be updated in the PostUpdate event handler to reflect the view port positions.
</div><p class="heading1a">Custom Parameters in AJAX Requests and Responses</p><div class="content">
Apart from the view port state, in some cases, other custom parameters may be required to determine how to update the chart. For example, in a finance chart application, the server may need to know the "ticker symbol" to determine which data series to draw, and the "ticker symbol" can be controlled by the user through an HTML text box on the web page. In this case, during AJAX chart update, the contents of the HTML text box would also need to be sent to the server.<br><br>
Similarly, in some cases, apart from updating the chart, the server may want to update other things in the web page. In this case, custom parameters would need to be sent from the server to the browser.<br><br>
In ChartDirector, <a href="WebChartViewer.setCustomAttr.htm">WebChartViewer.setCustomAttr</a>, <a href="WebChartViewer.getCustomAttr.htm">WebChartViewer.getCustomAttr</a>, <a href="JsChartViewer.setCustomAttr.htm">JsChartViewer.setCustomAttr</a> and <a href="JsChartViewer.getCustomAttr.htm">JsChartViewer.getCustomAttr</a> can be used to transfer custom parameters between the server and the browser during an AJAX chart update.<br><br>
In typical usage, to transfer parameters from the browser to the server, one may use <a href="JsChartViewer.setCustomAttr.htm">JsChartViewer.setCustomAttr</a> in a <a href="JsChartViewer.PreUpdate.htm">JsChartViewer.PreUpdate</a> event. The PreUpdate event occurs just before an AJAX chart update, so any parameters set will be transferred immediately to the server. On the server side, <a href="WebChartViewer.getCustomAttr.htm">WebChartViewer.getCustomAttr</a> can be used to retrieve the parameters. If the server needs to transfer custom parameters to the browser side, it can use <a href="WebChartViewer.setCustomAttr.htm">WebChartViewer.setCustomAttr</a>. The browser can retrieve the parameters using <a href="JsChartViewer.getCustomAttr.htm">JsChartViewer.getCustomAttr</a> in a <a href="JsChartViewer.PostUpdate.htm">JsChartViewer.PostUpdate</a> event, which occurs immediately after the browser receives an AJAX response from the server.
</div><p class="heading1a">Managing Axis Scale</p><div class="content">
The view port always assumes the full data range to be 0 to 1. In practice, a chart can have multiple x-axes and y-axes, using a combination of date/time, linear and logarithmic scales.<br><br>
To facilitate conversion between the view port and the axis scale, ChartDirector includes a number of methods as follows:<br><br>
<div class="overflowblock"> <div style="width:100%;box-sizing:border-box;"><table width="100%" border="1" cellpadding="5" cellspacing="0"> <tr><th width="33%">Method<th>Description
<tr><td><a href="WebChartViewer.setFullRange.htm">WebChartViewer.setFullRange</a><td>Defines the full range of a view port data scale. <tr><td><a href="WebChartViewer.getValueAtViewPort.htm">WebChartViewer.getValueAtViewPort</a><br><a href="JsChartViewer.getValueAtViewPort.htm">JsChartViewer.getValueAtViewPort</a><td>Converts a view port coordinate to a value of the specified data scale. <tr><td><a href="WebChartViewer.getViewPortAtValue.htm">WebChartViewer.getViewPortAtValue</a><br><a href="JsChartViewer.getViewPortAtValue.htm">JsChartViewer.getViewPortAtValue</a><td>Converts a value of the specified data scale to a view port coordinate. <tr><td><a href="WebChartViewer.syncLinearAxisWithViewPort.htm">WebChartViewer.syncLinearAxisWithViewPort</a><td>Synchronizes a linear Axis with the part of the data scale in view port. <tr><td><a href="WebChartViewer.syncLogAxisWithViewPort.htm">WebChartViewer.syncLogAxisWithViewPort</a><td>Synchronizes a logarithmic Axis with the part of the data scale in view port. <tr><td><a href="WebChartViewer.syncDateAxisWithViewPort.htm">WebChartViewer.syncDateAxisWithViewPort</a><td>Synchronizes a date/time Axis with the part of the data scale in view port.
</table></div> </div><br>
In typical usage, <a href="WebChartViewer.setFullRange.htm">WebChartViewer.setFullRange</a> is used to define the full data ranges for the axes in the chart. <a href="WebChartViewer.getValueAtViewPort.htm">WebChartViewer.getValueAtViewPort</a> and <a href="WebChartViewer.getViewPortAtValue.htm">WebChartViewer.getViewPortAtValue</a> can then be used to map between data values and view port positions. <a href="WebChartViewer.syncLinearAxisWithViewPort.htm">WebChartViewer.syncLinearAxisWithViewPort</a>, <a href="WebChartViewer.syncLogAxisWithViewPort.htm">WebChartViewer.syncLogAxisWithViewPort</a> and <a href="WebChartViewer.syncDateAxisWithViewPort.htm">WebChartViewer.syncDateAxisWithViewPort</a> can be used to synchronize the axis scale with the view port position.<br><br>
If <a href="WebChartViewer.syncLinearAxisWithViewPort.htm">WebChartViewer.syncLinearAxisWithViewPort</a>, <a href="WebChartViewer.syncLogAxisWithViewPort.htm">WebChartViewer.syncLogAxisWithViewPort</a> or <a href="WebChartViewer.syncDateAxisWithViewPort.htm">WebChartViewer.syncDateAxisWithViewPort</a> is called without first defining the full data range, ChartDirector will automatically configure the axis scale based on the data in the chart, and assume it to be the full data range. This is useful if the full data range is not known but must be inferred from the data.
</div><p class="heading1a">Server Side Code Structure</p><div class="content">
The server side code needs to handle both the initial page request and subsequent AJAX chart updates. The first thing it needs to do is to distinguish which type of requests it is handling, so that it can execute the appropriate code. <a href="WebChartViewer.isPartialUpdateRequest.htm">WebChartViewer.isPartialUpdateRequest</a> can be used to detect if the current HTTP request is an AJAX chart update request.
</div><p class="heading2">Initial Page Request</p><div class="content">
The initial page request is just a normal page request, and can be handled just like a normal web page request.
</div><p class="heading2">AJAX Chart Updates</p><div class="content">
In an AJAX chart update, only the chart needs to be updated. The server should return an AJAX response using <a href="WebChartViewer.partialUpdateChart.htm">WebChartViewer.partialUpdateChart</a> instead of the full web page.<br><br>
Note that HTTP GET or POST parameters in the initial page request no longer exists in subsequent AJAX chart updates. If these parameters are necessary in AJAX chart updates, they should be saved as custom attributes using <a href="WebChartViewer.setCustomAttr.htm">WebChartViewer.setCustomAttr</a> during initial page request. As custom attributes are persistent across AJAX chart updates, they can be retrieved using <a href="WebChartViewer.getCustomAttr.htm">WebChartViewer.getCustomAttr</a> and used in charting code.
</div><p class="heading1a">Browser Side Code Structure</p><div class="content">
On the browser side, the typical code structure is:<br><br>
<ul>
<li>Include the ChartDirector Javascript Library "cdjcv.js" in the web page. This is typically by inserting the following code in the &lt;HEAD&gt; block of the page.<br><br>
<div class="indentedblock"><code>&lt;script type=<wbr>"text/<wbr>javascript" src=<wbr>"cdjcv.js"&gt;&lt;/<wbr>script&gt;</code></div><br>
<li>Include code to initialize the JsChartViewer after the web page has loaded. This is typically done by performing the initialization function in the onload event handler of the window object or the &lt;BODY&gt; tag. A typical example is:<br><br>
<div class="codeblock"><code class='pre'>//
// Execute the following initialization code after the web page is loaded
//
JsChartViewer.addEventListener(window, 'load', function() {

    // Get the Javascript ChartViewer object (please replace idOfChartViewer below with
    // the real id used in your code)
    var viewer = JsChartViewer.get('idOfChartViewer');

    // Update the chart when the view port has changed (eg. when the user zooms in using the mouse)
    viewer.attachHandler("ViewPortChanged", viewer.partialUpdate);

    // Set the zoom and scroll mode to horizontal
    viewer.setScrollDirection(JsChartViewer.Horizontal);
    viewer.setZoomDirection(JsChartViewer.Horizontal);

    // Set the initial mouse usage to "scroll"
    viewer.setMouseUsage(JsChartViewer.Scroll);
    document.getElementById("scrollChart").checked = true;
});</code></div><br>
<li>If there are <a href="JsChartViewer.PreUpdate.htm">JsChartViewer.PreUpdate</a> and <a href="JsChartViewer.PostUpdate.htm">JsChartViewer.PostUpdate</a> event handlers, they can also be set up during initialization.<br></ul>
</div><p class="heading1a">Library Files Required for Zoomable/Scrollable Charts</p><div class="content">
A zoomable/scrollable chart requires the following files. Please ensure you copy the necessary files to the proper directories (typically the same directory as the script) and reference them using the proper paths.<br><br>
<div style="width:100%;box-sizing:border-box;"><table width="100%" border="1" cellpadding="5" cellspacing="0"> <tr><th width="24%">File<th>Description
<tr><td>getchart.jsp<td>The standard utility script used in the &lt;IMG&gt; tag URL for retrieving the chart image from
<tr><td>cdjcv.js<br>zoomin.cur<br>zoomout.cur<br>nozoom.cur<br>wait.gif<td>The script file for <a href="JsChartViewer.htm">JsChartViewer</a> and the supporting cursor and image files. They must be in the same directory.
</table></div></div><p class="heading1a">Zooming and Scrolling Examples</p><div class="content">
<div style="width:100%;box-sizing:border-box;"><table width="100%" border="1" cellpadding="5" cellspacing="0"> <tr><th width="33%">Sample Code<th>Description
<tr><td><a href="simplezoomscrollweb.htm">Simple Zooming and Scrolling</a><td>A simple zoomable and scrollable chart with tooltips, using mouse click and drag to control zooming and scrolling.
<tr><td><a href="zoomscrolltrackweb.htm">Zooming and Scrolling with Track Line</a><td>Besides using mouse click and drag for zooming and scrolling, this example has buttons for jumping immediately to display data for the last 30 days, last 90 days, last year or all time. There are check boxes to select the data series to plot, and an update button to immediately update the chart. In addition, the chart includes a track cursor that updates the legend dynamically to display the data values as the mouse cursor moves over the chart.
<tr><td><a href="viewportcontroldemoweb.htm">Zooming and Scrolling with Viewport Control</a><td>The example extends the <a href="zoomscrolltrackweb.htm">Zooming and Scrolling with Track Line</a> example by adding a <a href="WebViewPortControl.htm">WebViewPortControl</a> to visualize and control the viewport, and a button to download the chart as PDF.
<tr><td><a href="xyzoomscrollweb.htm">XY Zooming and Scrolling</a><td>This example demonstrates zooming and scrolling in both horizontal and vertical directions. In addition to using mouse click and drag, this example demonstrates using a <a href="WebViewPortControl.htm">WebViewPortControl</a> to visualize and control the viewport. There is also an image map for data point tooltips.
</table></div></div><br>
<hr class="separator"><div class="copyright">&copy; 2022 Advanced Software Engineering Limited. All rights reserved.</div></body>
</HTML>
